{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    }
   },
   "source": [
    "# Inflating and Converting Currency"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notice\n",
    "\n",
    "This notebook's section on `convert_currency` has been disabled, as `exchangeratesapi.io` has disabled pinging of its API without an API key."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    }
   },
   "source": [
    "## Background"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    }
   },
   "source": [
    "This notebook serves to show a brief and simple example of how to use the `convert_currency()` and `inflate_currency()` methods from pyjanitor's finance submodule.\n",
    "\n",
    "The data for this example notebook come from the [United States Department of Agriculture Economic Research Service](https://www.ers.usda.gov/data-products/food-expenditure-series/), and we are specifically going to download the data of nominal food and alcohol expenditures, with taxes and tips, for all purchasers.  The data set includes nominal expenditures for 1997-2018, and the expenditures are provided in **millions** of U.S. dollars for the year in the which the expenditures were made.  For example, the expenditure values for 1997 are in units of 1997 U.S. dollars, whereas expenditures for 2018 are in 2018 U.S. dollars."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting and Cleaning the Data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "url = (\n",
    "    \"https://www.ers.usda.gov/webdocs/DataFiles/50606/nominal_expenditures.csv?v=9289.4\"\n",
    ")\n",
    "# 1) Read in the data from .csv file\n",
    "# 2) Clean up the column names\n",
    "# 3) Remove any empty rows or columns\n",
    "# 4) Melt the dataframe (from wide to long) to obtain \"tidy\" format\n",
    "data = (\n",
    "    pd.read_csv(url, usecols=[0, 1, 2, 3, 4, 5, 6, 7, 8, 9], nrows=22, thousands=\",\")\n",
    "    .clean_names()\n",
    "    .remove_empty()\n",
    "    .melt(id_vars=[\"year\"], var_name=\"store_type\", value_name=\"expenditure\")\n",
    ")\n",
    "data.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use inflate_currency() to Inflate All Values to 2018$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Use split-apply-combine strategy to obtain 2018$ values\n",
    "# Group the data frame by year\n",
    "grouped = data.groupby([\"year\"])\n",
    "# Apply the inflate_currency() method to each group\n",
    "# (Note that each group comes with a name; in this case,\n",
    "#  the name corresponds to the year)\n",
    "data_constant_dollar = grouped.apply(\n",
    "    lambda x: x.inflate_currency(\n",
    "        column_name=\"expenditure\",\n",
    "        country=\"USA\",\n",
    "        currency_year=int(x.name),\n",
    "        to_year=2018,\n",
    "        make_new_column=True,\n",
    "    )\n",
    ")\n",
    "data_constant_dollar.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot Time Series to Observe Currency Inflation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Plot time series of nominal and real (2018$) expenditures for grocery stores\n",
    "# Note that the 2018 values for both series should be equal\n",
    "(\n",
    "    data_constant_dollar.loc[\n",
    "        data_constant_dollar[\"store_type\"].str.contains(\"grocery_stores\"), :\n",
    "    ]\n",
    "    .set_index(\"year\")\n",
    "    .drop(columns=\"store_type\")\n",
    "    .plot()\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Use convert_currency() to Convert USD to British Pounds\n",
    "\n",
    "_Note: Disabled and commented out due to `exchangeratesapi.io` policies.\n",
    "We are working through the deprecation of the API._"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "# # Apply the convert_currency() method to the 'expenditure_2018' column\n",
    "# # Use the exchange rate from Dec. 31, 2018, since our data are in 2018$\n",
    "# data_constant_pounds = (\n",
    "#     data_constant_dollar\n",
    "#     .convert_currency(\n",
    "#         api_key=\"a8ef744de81e4bd3908e2acf5a137c3a\",\n",
    "#         column_name='expenditure_2018',\n",
    "#         from_currency='USD',\n",
    "#         to_currency='GBP',\n",
    "#         historical_date=date(2018, 12, 31),\n",
    "#         make_new_column=True\n",
    "#     )\n",
    "# )\n",
    "# data_constant_pounds.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot Time Series to Observe Currency Conversion"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    }
   },
   "outputs": [],
   "source": [
    "# # You can see from this plot that GBP were worth more than USD on Dec. 31, 2018\n",
    "# # (by about 1.3x, it appears)\n",
    "# (\n",
    "#     data_constant_pounds\n",
    "#     .loc[data_constant_pounds['store_type'].str.contains('grocery_stores'), :]\n",
    "#     .set_index('year')\n",
    "#     .drop(columns='store_type')\n",
    "#     .plot()\n",
    "# )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    }
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "pyjanitor-dev",
   "language": "python",
   "name": "pyjanitor-dev"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.8"
  },
  "nbsphinx": {
   "execute": "never"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
